Label Replace API Documentation

Eparcel换单交邮接口文档

目录

接口概述

该接口用于处理标签替换请求，允许客户端提交中性面单号及其他相关信息来请求替换标签，支持正常换单和取消换单功能。同时提供批量查询换单状态的功能，支持输入多个中性面单或尾程单号，查询换单是否成功及成功时间。

环境URL

生产环境：https://lr.tooexp.com

测试环境：http://172.232.21.79:5002

标签替换接口

请求信息

URL

POST /api/tag/label-replace

请求方法

POST

请求头

Content-Type: application/json
customerCode: string // 客户代码
apiKey: string // API密钥
头字段名 类型 必填 描述
Content-Type string 是 请求体类型，固定为application/json
customerCode string 否 客户代码，用于API身份验证
apiKey string 否 API密钥，用于API身份验证

请求参数

字段名 类型 必填 长度限制 描述
BillOfLadingNumber string 否 100字符 空运提单号或者国际快递单号
MasterPackageNumber string 否 100字符 大包号(大箱号)
ReferenceNumber string 否 100字符 参考号（一般表示订单号）
NeutralWaybillNumber string 是 100字符 中性面单单号（必填）
FinalMileTrackingNumber string 否 100字符 尾程跟踪单号
Label string 否 无限制 标签内容（一般为PDF，可能是base64或其他格式）
ReplaceStatus string 否 1字符 换单状态（Y表示正常换单，N表示取消换单，默认为Y）

请求示例

正常换单请求
{
  "BillOfLadingNumber": "BL12345678",
  "MasterPackageNumber": "MP98765432",
  "ReferenceNumber": "ORD123456",
  "NeutralWaybillNumber": "NW1234567890",
  "FinalMileTrackingNumber": "FM1234567890",
  "Label": "base64_encoded_pdf_content",
  "ReplaceStatus": "Y"
}
取消换单请求
{
  "NeutralWaybillNumber": "NW1234567890",
  "ReplaceStatus": "N"
}
修改数据请求
{
  "NeutralWaybillNumber": "NW1234567890",
  "BillOfLadingNumber": "BL87654321",
  "MasterPackageNumber": "MP23456789",
  "ReferenceNumber": "ORD654321",
  "FinalMileTrackingNumber": "FM9876543210"
}

响应信息

成功响应

响应状态码

200 OK

响应头
Content-Type: application/json
响应参数
字段名 类型 描述
status string 状态，成功为"ok"
timestamp string 响应时间戳（UTC）
neutralWaybillNumber string 请求中的中性面单单号
replaceStatus string 实际使用的换单状态
labelReplaced boolean 标签是否成功替换（正常换单为true，取消换单为false）
message string 响应消息
成功响应示例
正常换单响应
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement request processed successfully"
}
取消换单响应
{
  "status": "ok",
  "timestamp": "2026-01-13T12:34:56",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "N",
  "labelReplaced": false,
  "message": "Label replacement request has been frozen"
}
修改数据成功响应
{
  "status": "ok",
  "timestamp": "2026-01-20T14:30:00",
  "neutralWaybillNumber": "NW1234567890",
  "replaceStatus": "Y",
  "labelReplaced": true,
  "message": "Label replacement data updated successfully"
}

错误响应

响应状态码

400 Bad Request

错误响应示例
缺少必填字段
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
请求体为空
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
无效的换单状态
{
  "status": "error",
  "message": "Invalid replace status. Use 'Y' for normal replacement or 'N' for frozen replacement"
}
标签已返回无法修改
{
  "status": "error",
  "message": "Label has been returned and cannot be modified"
}
服务器错误
{
  "status": "error",
  "message": "具体错误信息"
}

批量查询批量查询换单结果接口换单状态接口

请求信息

URL

POST /api/label/label-replace/status

请求方法

POST

请求头

Content-Type: application/json
customerCode: string // 客户代码（必填）
apiKey: string // API密钥（必填）
头字段名 类型 必填 描述
Content-Type string 是 请求体类型，固定为application/json
customerCode string 是 客户代码，用于API身份验证
apiKey string 是 API密钥，用于API身份验证

请求参数

字段名 类型 必填 描述
numbers array 是 单号列表（中性面单或尾程单号）

请求示例

查询多个单号
{
  "numbers": ["NW1234567890", "FM9876543210", "NW1122334455"]
}

响应信息

成功响应

响应状态码

200 OK

响应头
Content-Type: application/json
响应参数
字段名 类型 描述
code integer HTTP响应码，成功为200
timestamp string 响应时间戳（UTC）
count integer 返回的结果数量
data array 换单状态查询结果列表
data数组元素结构
字段名 类型 描述
WaybillNumber string 中性面单单号
TrackingNumber string 尾程跟踪单号
Replaced boolean 是否换单成功
ReplacedAt string 换单成功时间（UTC），未成功则为null
成功响应示例
{
  "code": 200,
  "timestamp": "2026-03-10T12:34:56",
  "count": 3,
  "data": [
    {
      "WaybillNumber": "NW1234567890",
      "TrackingNumber": "FM1234567890",
      "Replaced": true,
      "ReplacedAt": "2026-03-10T10:15:30"
    },
    {
      "WaybillNumber": "NW9876543210",
      "TrackingNumber": "FM9876543210",
      "Replaced": false,
      "ReplacedAt": null
    },
    {
      "WaybillNumber": "",
      "TrackingNumber": "FM1122334455",
      "Replaced": true,
      "ReplacedAt": "2026-03-09T14:20:15"
    }
  ]
}

错误响应

响应状态码

200 OK（错误信息在响应体中）

错误响应示例
缺少认证信息
{
  "code": 400,
  "message": "customerCode and apiKey are required in headers"
}
无效的认证信息
{
  "code": 401,
  "message": "Invalid API credentials. Please check your customerCode and apiKey."
}
缺少查询参数
{
  "code": 400,
  "message": "Numbers parameter is required"
}
服务器错误
{
  "code": 500,
  "message": "An unexpected error occurred.",
  "errorDetails": "具体错误信息"
}

注意事项

  1. 必填字段：必须提供NeutralWaybillNumber字段
  2. 换单状态：如果提供ReplaceStatus字段，只能是"Y"或"N"，默认为"Y"
  3. 数据格式：所有字符串字段应确保格式正确
  4. 标签内容：如果提供Label字段，应确保其为有效的格式（如base64编码的PDF）
  5. 并发处理：接口设计支持并发请求，每个请求相互独立
  6. 错误处理：所有错误都会返回适当的HTTP状态码和详细的错误消息
  7. 修改支持：接口支持通过提供NeutralWaybillNumber来修改已存在的订单数据
  8. 修改限制：如果标签已被返回（即该订单存在扫描结果为"已返回面单"的记录），则无法修改该订单数据
  9. 字段长度：除Label字段外，所有字符串字段的长度限制为100字符